Unity SDK

Overview

The WebAR³ VPS Unity SDK lets you localize users within configured VPS maps and place content with centimeter-level accuracy on ARKit (iOS) and ARCore (Android) devices. This page mirrors the structure of the Immersal docs—scan the prerequisites, install the package, wire the scene, and start localization.

Prerequisites

• Unity 2022.3 LTS or newer
• Test device with ARKit or ARCore support
• Git LFS if you plan to clone the sample project (large assets)

Install Options

Clone the sample project

git clone https://github.com/WebAR-Studio/was-vps-unity.git

Open the project in Unity 2022.3+. Scenes under Assets/Scenes contain reference setups.

Add via Package Manager

1. Go to Window → Package Manager.
2. Select the + button → Add package from Git URL….
3. Paste https://github.com/WebAR-Studio/was-vps-unity.git?path=/Assets.

Unity downloads the SDK into Packages/was-vps-unity.

Project Setup

1. Create or open an AR Foundation–ready scene (contains AR Session and AR Session Origin).
2. Add VPSLocalisationService to an empty GameObject; this component drives the localization loop.
3. Assign required references in the inspector:
   • AR Session
   • AR Session Origin
   • Optional AR camera and UI hooks (follow the sample scenes).
4. Fill in your VPS API Key and at least one Location ID.

   Need an API key? Grab one at space.web-ar.studio or email support@webar3.com / support@web-ar.studio.

5. (Optional) Enable Save Images Locally or Save Logs In File while you debug.

Start Localization

The SDK exposes a concise API so you can control localization from your scripts. Attach the component below and assign the VPSLocalisationService reference in the inspector.

using UnityEngine;
using WASVPS;

public class VPSBootstrap : MonoBehaviour
{
    [SerializeField] private VPSLocalisationService vpsService;

    private void Start()
    {
        vpsService.OnPositionUpdated += HandlePositionUpdated;
        vpsService.OnErrorHappend += HandleError;

        var settings = new SettingsWASVPS(
            new[] { "your-location-id" },
            failsCountToReset: 5
        );

        settings.ApiKey = "your-api-key";
        settings.LocalizationTimeout = 2.0f;

        vpsService.StartVPS(settings);
    }

    private void HandlePositionUpdated(LocationState state)
    {
        Debug.Log($"Localized at {state.Localisation.VpsPosition}");
    }

    private void HandleError(ErrorInfo error)
    {
        Debug.LogError(error.LogDescription());
    }
}

Inspector Reference

Property	Purpose	Default
Start On Awake	Automatically start localization when the scene loads	false
Force Mock In Editor	Always use the mock provider while running in the Editor	true
Send GPS	Attach device GPS data to each VPS request	false
Fails Count To Reset	Number of consecutive failures before the session resets	5
Save Images Locally	Persist captured frames for debugging	false

Debugging & Testing

• Enable Force Mock In Editor and use the supplied mock textures to iterate without a connected device.
• Call VPSLogger.SetLogLevel(LogLevel.VERBOSE) to review HTTP requests, responses, and error payloads in the console.
• If localization never succeeds, confirm that your API key is valid and that each location ID matches an available VPS map.

Next Steps

• Explore Assets/Scenes/TestScene.unity and Assets/Scripts/ExampleVPS.cs in the sample project for reference implementations.
• Combine VPS poses with your own logic for spawning anchors, aligning 3D content, or driving UI updates.